Version: 2.0

Send Message

This section describes how you can send messages via WhatsApp with Sinch India WhatsApp API. The message endpoint is used as the primary endpoint of the API and this is where all the messages are sent.

Enterprise can subscribe to Opt-In/Opt-Out service before sending any messages. For more information on the Opt-In and Opt-Out requirements for WhatsApp messages, please refer User Consent.
Businesses can only initiate a new conversation for a specific category with a defined approved WhatsApp template. Templates can be created on the Sinch SmartTA Dashboard.

Message object types

Following are the types of messages that can be sent on WhatsApp:

Text Messages
Media Messages
Contacts and Location Messages
Interactive Messages: List Messages, Reply Buttons, Single Product Messages, Multi-Product Messages and Catalog Messages
Message Templates
Media Message Templates
Interactive Message Templates

Before You Start

You need:

Authenticate yourself and receive an authentication token that enables you to access the service. See the Token Based Authentication for more information on how to do this.
You send messages by making a POST call to Sinch India API end-point regardless of message type. The content of the JSON message body differs for each type of message (text, image, etc.).

Constraints

The following types of message are supported: text, message templates, images, documents and audio.
A text message can be a max of 4096 characters long

Creating

You send messages by making a POST call to the /pull-platform-receiver/v2/wa/messages node regardless of message type. The content of the JSON message body differs for each type of message (text, image, etc.).

Send a WhatsApp message

Request type: POST

For Token-based authentication method:

Production / Live API: https://api.aclwhatsapp.com/pull-platform-receiver/v2/wa/messages
UAT API: https://apiuat.aclwhatsapp.com/pull-platform-receiver/v2/wa/messages

For Password-based authentication (To be deprecated going forward)

Production / Live API: https://push.aclwhatsapp.com/pull-platform-receiver/v2/wa/messages

UAT API: https://pushuat.aclwhatsapp.com/pull-platform-receiver/wa/v2/messages

Parameters

These are the main parameters used in /pull-platform-receiver/v2/wa/messages POST requests:

Name	Description
audio object	Required when type=audio. A media object containing audio.
contacts object	Required when type=contacts. A contacts object.
context object	Required if replying to any message in the conversation. An object containing the ID of a previous message you are replying to. For example: { "message_id": "MESSAGE_ID" }.
document object	Required when type=document. A media object containing a document.
image object	Required when type=image. A media object containing an image.
interactive object	Required when type=interactive. An interactive object. The components of each interactive object generally follow a consistent pattern: header, body, footer, and action.
location object	Required when type=location. A location object.
messaging_product string	Required. Messaging service used for the request. Use "whatsapp".
preview_url boolean	Required if type=text. Allows for URL previews in text messages. This field is optional if not including a URL in your message. Values: false (default), true. On-Premises API only. Cloud API users can use the same functionality with the preview_url field inside a text object.
recipient_type string	Optional. Currently, you can only send messages to individuals. Set this as individual. Default: individual
template object	Required when type=template. A template object.
text object	Required for text messages. A text object.
to string	Required. WhatsApp ID or phone number of the customer you want to send a message to.
type string	Optional. The type of message you want to send. If omitted, defaults to text.

Parameters for Metadata

Below are optional metadata parameters used in /pull-platform-receiver/v2/wa/messages POST requests:

Name	Description
to String	Optional. Recipient no.
messageId String	Optional. Message Id.
brd String	Optional. Campaign Id.
transactionId String	Optional. Transaction Id.
callbackDlrUrl String	Optional. Callback Dlr Url.
SinchReserved Object	Optional. SinchReserved data.

Parameters for SinchReserved

Below are optional SinchReserved parameters used in /pull-platform-receiver/v2/wa/messages POST requests:

Name	Description
responseId String	Optional. Response Id.
PaymentReferenceId String	Optional. Payment Reference Id.
requestReceivedTime String	Optional. Request Received Time.

Text Object

Name	Description
body	Required. Contains the text of the message, which can contain URLs and formatting.

Media Object

For the On-Premises API, the media object id is returned when the media is successfully uploaded to the WhatsApp Business on-premises/reference client via the media endpoint.

Name	Description
id string	Required when type is audio, document, image, sticker, or video and you are not using a link. The media object ID. Do not use this field when message type is set to text.
link string	Required when type is audio, document, image, sticker, or video and you are not using an uploaded media ID (i.e. you are hosting the media asset on your public server). The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. Do not use this field when message type is set to text. Cloud API users only: • When we request the media asset from your server you must indicate the media's MIME type by including the Content-Type HTTP header. For example: Content-Type: video/mp4.
caption string	Optional. Media asset caption. Do not use with audio or sticker media. On-Premises API users: • For v2.41.2 or newer, this field is limited to 1024 characters. • Captions are currently not supported for document media.
filename string	Optional. Describes the filename for the specific document. Use only with document media. The extension of the filename will specify what format the document is displayed as in WhatsApp.
provider string	Optional. On-Premises API only. This path is optionally used with a link when the HTTP/HTTPS link is not directly accessible and requires additional configurations like a bearer token.

Contacts Object

Inside contacts, you can nest the following objects: addresses, emails, name, org, phone, and urls. Pluralized objects are to be wrapped in an array as shown in the example below.

Name	Description
addresses Object	Optional. Full contact address(es) formatted as an addresses object. The object can contain the following fields: street string – Optional. Street number and name. city string – Optional. City name. state string – Optional. State abbreviation. zip string – Optional. ZIP code. country string – Optional. Full country name. country_code string – Optional. Two-letter country abbreviation. type string - Optional. Standard values are HOME and WORK.
birthday Object	Optional. YYYY-MM-DD formatted string.
emails Object	Optional. Contact email address(es) formatted as an emails object. The object can contain the following fields: email string – Optional. Email address. type string – Optional. Standard values are HOME and WORK.
name Object	Required. Full contact name formatted as a name object. The object can contain the following fields: formatted_name string Required. Full name, as it normally appears. first_name string- Optional. First name last_name string- Optional. Last name. middle_name string - Optional. Middle name. suffix string- Optional. Name suffix. prefix string- Optional. Name prefix. *At least one of the optional parameters needs to be included along with the formatted_name parameter.
org Object	Optional. Contact organization information formatted as an org object. The object can contain the following fields: company string- Optional. Name of the contact's company. department string- Optional. Name of the contact's department. title string- Optional. Contact's business title.
phones Object	Optional. Contact phone number(s) formatted as a phone object. The object can contain the following fields: phone string- Optional. Automatically populated with the wa_id value as a formatted phone number. type string- Optional. Standard Values are CELL, MAIN, IPHONE, HOME, and WORK. wa_id string- Optional. WhatsApp ID.
urls Object	Optional. Contact URL(s) formatted as a urls object. The object can contain the following fields: url string- Optional. URL. type string- Optional. Standard values are HOME and WORK.

Location Object

Name	Description
latitude	Required. Location latitude in decimal degrees.
longitude	Required. Location longitude in decimal degrees.
name	Required. Name of the location.
address	Required. Address of the location.

Template Object

Inside template, you can nest the components and the language objects.

info

Beginning in v2.27.8, a template's namespace must be the namespace associated with the WABA that owns the phone number in the current WhatsApp Business on-prem client. Otherwise, the message will fail to send.

In addition, from v2.41 and onwards, namespace will be an optional field.

Name	Description
name	Required. Name of the template.
language Object	Required. Contains a language object. Specifies the language the template may be rendered in. The language object can contain the following fields: policy string
components array of objects	Optional. Array of components objects containing the parameters of the message.
namespace	Optional. Only used for On-Premises API. Namespace of the template.

Components Object
Inside components, you can nest the parameters object. Additionally, you can set type to button.

Name	Description
type string Supported Options	Required. Describes the component type. header body button For text-based templates, we only support the type=body.
sub_type string Supported Options	Required. Required when type=button. Not used for the other types. Type of button to create. quick_reply: Refers to a previously created quick reply button that allows for the customer to return a predefined message. url: Refers to a previously created button that allows the customer to visit the URL generated by appending the text parameter to the predefined prefix URL in the template. catalog: Refers to a previously created catalog button that allows for the customer to return a full product catalog.
parameters array of objects	Required when type=button. Array of parameters objects with the content of the message. For components of type=button, see the button parameter object.
index	Required when type=button. Not used for the other types. Position index of the button. You can have up to 10 buttons using index values of 0 to 9.

Parameter Object

Name	Description
type	Required. Describes the parameter type. Values: text, currency, date_time, image, document, video.

Button Type
Inside the components object, you can set type to button. These are the button parameters:

Name	Description
type	Required. Describes the parameter type. Values: quick_reply, url, copy_code (available from 2.49 and onwards).
index	Required. Position index of the button. You can have up to 10 buttons using index values of 0-9.
parameters	Required. The parameters for the button, which are set at creation time in your Business Manager. Include the following parameters: type(Required): Indicates the type of parameter for the button. Supported values are payload, text, coupon_code payload (Required for quick_reply buttons): Developer-defined payload that will be returned when the button is clicked in addition to the display text on the button. text (Required for url buttons): Developer provided suffix that will be appended to a previously created dynamic URL button. coupon_code (Required for copy_code buttons) (available from 2.49 and onwards): Developer provided coupon code which gets copied when the copy code button is clicked.

Example of button type with sub_type quick_reply:

{
    "type": "button",
    "sub_type": "quick_reply",
    "index": 0,
    "parameters": [
        {
            "type": "payload",
            "payload": "Yes-Button-Payload"
        }
    ]
}

Example of button type with sub_type copy_code:

{
    "type": "button",
    "sub_type": "copy_code",
    "index": 0,
    "parameters": [
        {
            "type": "coupon_code",
            "coupon_code": "DISCOUNT20"
        }
    ]
}

Interactive Object

The interactive object generally contains 4 main components: header, body, footer, and action. Additionally, some of those components can contain one or more different objects:

Inside header, you can nest media objects.
Inside action, you can nest section and button objects.

Name	Description
type	Required. The type of interactive message you want to send. Supported values: list: Use it for List Messages. button: Use it for Reply Buttons. product: Use it for Single-Product Messages. product_list: Use it for Multi-Product Messages. catalog_message: Use it for Catalog Messages. flow: Use it for Flows Messages.
header	Required for type product_list. Optional for other types. Header content displayed on top of a message. You cannot set a header if your interactive object is of product type. The header object contains the following fields: document object – Required if type is set to document. Contains the media object with the document. image object – Required if type is set to image. Contains the media object with the image. video object – Required if type is set to video. Contains the media object with the video. text string – Required if type is set to text. Text for the header. Formatting allows emojis, but not markdown. Maximum length: 60 characters. type string – Required. The header type you would like to use. Supported values are: text – for List Messages, Reply Buttons, and Multi-Product Messages. video – for Reply Buttons. image – for Reply Buttons. document – for Reply Buttons.
body	Optional for type product. Required for other message types. An object with the body of the message. The body object contains the following field: text string – Required if body is present. The content of the message. Emojis and markdown are supported. Maximum length: 1024 characters.
footer	Optional. An object with the footer of the message. The footer object contains the following field: text string – Required if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length: 60 characters.
action	Required. An action object with what you want the user to perform after reading the message.

Action Object

Name	Description
button	Required for List Messages. Button content. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters.
buttons	Required for Reply Button Messages. A button object. The object can contain the following parameters: type – The only supported option is reply for Reply Button Messages. title – Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. id – Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 256 characters. You cannot have leading or trailing spaces when setting the ID.
sections	Required for List Messages and Multi-Product Messages. Array of section objects. There is a minimum of 1 and maximum of 10.
catalog_id	Required for Single-Product Messages and Multi-Product Messages. Unique identifier of the Facebook catalog linked to your WhatsApp Business Account. This ID can be retrieved via Commerce Manager.
product_retailer_id	Required for Single-Product Messages and Multi-Product Messages. Unique identifier of the product in a catalog. Maximum 100 characters for both Single-Product and Multi-Product messages.
mode	Optional for Flows Messages. The current mode of the Flow, either draft or published. Default: published.
flow_message_version	Required for Flows Messages. Must be 3.
flow_token	Required for Flows Messages. A token that is generated by the business to serve as an identifier.
flow_id	Required for Flows Messages. Unique identifier of the Flow provided by WhatsApp.
flow_cta	Required for Flows Messages. Text on the CTA button, e.g., "Signup". Maximum length: 20 characters (no emoji).
flow_action	Optional for Flows Messages. navigate or data_exchange. Use navigate to predefine the first screen as part of the message. Use data_exchange for advanced use-cases where the first screen is provided by your endpoint. Default: navigate.
flow_action_payload	Optional for Flows Messages. Required only if flow_action is navigate. The object can contain the following parameters: screen – Required. The id of the first screen of the Flow. data – Optional. The input data for the first screen of the Flow. Must be a non-empty object.

Section Object

Name	Description
title	Required if the message has more than one section. Title of the section. Maximum length: 24 characters.
rows	Required for List Messages. Contains a list of row objects. Limited to 10 rows across all sections. Each row object contains the following fields: title– Required. Maximum length: 24 characters. ID – Required. Maximum length: 200 characters. description – Optional. Maximum length: 72 characters.
product_items	Required for Multi-Product Messages. Array of product objects. There is a minimum of 1 product per section and a maximum of 30 products across all sections. Each product object contains the following field: product_retailer_id – Required for Multi-Product Messages. Unique identifier of the product in a catalog.